SuiteQL Query Tool
Developer's Guide v2026.1

Welcome to the Developer's Guide for the SuiteQL Query Tool. This guide helps you understand the codebase architecture and learn SuiteScript development through a real-world, production-quality application.

Quick Start: Your First 5 Minutes

Want to see something working right away? Here's the fastest path to understanding how this tool works.

Step 1: Run Your First Query

Open the SuiteQL Query Tool and paste this simple query into the editor:

SELECT
    ID,
    CompanyName,
    Email
FROM
    Customer
WHERE
    ROWNUM <= 10

Click Run (or press Ctrl+Enter). You should see 10 customer records appear in the results.

Step 2: Understand What Happened

Here's what just occurred behind the scenes:

1. Your browser sent a POST request to the Suitelet with the query text
2. The Suitelet's handlePostRequest() function received it Line ~410
3. It called executeQuery() Line ~660 which used query.runSuiteQL() to execute your SQL
4. NetSuite returned the data, which was sent back as JSON
5. The browser JavaScript rendered the results in the table

Step 3: Find This in the Code

Open suiteql-query-tool.v2026.1.suitelet.js and search for:

• SECTION 4: QUERY EXECUTION Line ~651 - Where the query runs on the server
• query.runSuiteQL - The actual NetSuite API call
• function runQuery ~Line 7500 - The client-side JavaScript that sends the request

Step 4: Try Modifying

Now experiment! Try these modifications:

• Change Customer to Vendor or Employee
• Add more columns: Phone, DateCreated
• Change ROWNUM <= 10 to ROWNUM <= 25
• Add a filter: AND IsInactive = 'F'

Line Number Reference

This quick reference table helps you find key sections and functions in the production script. Keep this handy as you explore the code.

Major Sections

Key Server-Side Functions

Key Client-Side Functions (Inside Template Literal)

Purpose of This Guide

This Developer's Guide is designed to help you learn SuiteScript development by studying a real-world, production application. Rather than maintaining a separate "learning edition" with inline comments, this guide serves as a companion document you can reference alongside the production code.

Who Is This For?

• JavaScript developers new to NetSuite who want to understand SuiteScript
• NetSuite administrators looking to expand into development
• SuiteScript beginners who want to see patterns beyond "Hello World" examples
• Experienced developers looking for reference implementations of common patterns

What You'll Learn

• How to build custom user interfaces with Suitelets
• Executing SuiteQL queries with the N/query module
• File Cabinet operations with the N/file module
• Making external API calls with the N/https module
• Generating PDFs with the N/render module
• Session management and runtime information
• Client-server communication patterns
• Governance management and best practices

SuiteScript Primer

Before diving into the code, here's a quick overview of SuiteScript fundamentals.

What is SuiteScript?

SuiteScript is NetSuite's server-side JavaScript API. It allows you to customize and extend NetSuite's functionality through scripts that run on NetSuite's servers. SuiteScript 2.x (the current version) uses the AMD module pattern and supports modern JavaScript features.

JSDoc Decorators

Every SuiteScript file starts with special JSDoc comments that tell NetSuite how to handle the script. Look at the top of the production script Lines 1-5:

/**
 * @NApiVersion 2.1        // Use SuiteScript 2.1 (ES6+ JavaScript)
 * @NScriptType Suitelet   // This is a Suitelet (custom page/endpoint)
 * @NModuleScope Public    // Functions can be called from other scripts
 */

@NApiVersion

• 2.0 = SuiteScript 2.0 (ES5 JavaScript only)
• 2.1 = SuiteScript 2.1 (ES6+ features: const/let, arrow functions, template literals)

@NScriptType

The N/ Module System

SuiteScript functionality is organized into modules prefixed with "N/". You import these modules using the AMD define() function. See Lines 323-353 in the production script:

define([
    'N/query',      // SuiteQL queries
    'N/file',       // File Cabinet operations
    'N/runtime'     // Script/user/session info
], function(query, file, runtime) {
    // Your code here
    return {
        onRequest: myFunction
    };
});

Governance

Every SuiteScript operation consumes "governance units." Each script type has a limit:

Application Architecture

The SuiteQL Query Tool follows a client-server architecture where a single Suitelet serves both the HTML user interface and a JSON API.

Request Flow Diagram

+---------------------------------------------------------------------+
|                         USER'S BROWSER                               |
+---------------------------------------------------------------------+
        |                                          ^
        | 1. GET request                           | 2. HTML page with
        |    (initial page load)                   |    embedded JavaScript
        v                                          |
+---------------------------------------------------------------------+
|                           SUITELET                                   |
|  +-------------------------------------------------------------+    |
|  |  onRequest(context)                                          |    |
|  |    |-- GET  --> handleGetRequest()  --> serverWidget form    |    |
|  |    +-- POST --> handlePostRequest() --> JSON response        |    |
|  +-------------------------------------------------------------+    |
+---------------------------------------------------------------------+
        ^                                          |
        | 3. AJAX POST                             | 4. JSON data
        |    { function: 'queryExecute', ... }     |    { records: [...] }
        |                                          v
+---------------------------------------------------------------------+
|                    BROWSER JAVASCRIPT                                |
|  +-----------------+  +-----------------+  +-----------------+      |
|  | runQuery()      |  | loadSqlFile()   |  | callAI()        |      |
|  | --> fetch() POST|  | --> fetch() POST|  | --> fetch() POST|      |
|  +-----------------+  +-----------------+  +-----------------+      |
+---------------------------------------------------------------------+

Key Architectural Concepts

1. Dual-Purpose Suitelet

The Suitelet handles two types of requests (see Lines 354-430):

• GET requests return the full HTML page (the UI)
• POST requests act as API endpoints, returning JSON

2. INLINEHTML for Custom UI

Instead of using NetSuite's built-in form widgets, we inject a complete custom HTML application using the INLINEHTML field type. This gives us full control over the user interface. See ~Line 1650.

3. Client-Side JavaScript

The embedded JavaScript (starting at Line 5461) runs in the browser, not as SuiteScript. It uses standard web APIs like fetch() to communicate with the server. This is regular JavaScript with access to the DOM, localStorage, and third-party libraries.

4. Handler Dispatch Pattern

POST requests include a function property that tells the server which operation to perform. The server uses a dispatch table to route requests (see ~Lines 410-430):

const handlers = {
    'queryExecute': () => executeQuery(context, payload),
    'sqlFileLoad':  () => loadSqlFile(context, payload),
    'sqlFileSave':  () => saveSqlFile(context, payload),
    'aiGenerate':   () => generateAI(context, payload),
    // ... more handlers
};

const handler = handlers[payload.function];
if (handler) handler();

Code Roadmap

The production script is organized into numbered sections. Here's what each section contains:

Key Patterns to Study

These are the most instructive parts of the codebase for learning SuiteScript:

Beginner Basic Query Execution

Location: Section 4, executeQuery() function ~Line 439

Learn how to execute SuiteQL queries and handle the results:

const records = modules.query.runSuiteQL({
    query: 'SELECT ID, CompanyName FROM Customer WHERE IsInactive = ?',
    params: ['F']  // Parameterized query - prevents SQL injection!
}).asMappedResults();  // Returns array of objects

Beginner File Cabinet Operations

Location: Section 5 Lines 564-691

Learn how to read and write files in NetSuite's File Cabinet:

// Loading a file
const fileObj = modules.file.load({ id: fileId });
const contents = fileObj.getContents();

// Creating a file
const newFile = modules.file.create({
    name: 'query.sql',
    contents: sqlText,
    folder: folderId,
    fileType: modules.file.Type.PLAINTEXT
});
const savedId = newFile.save();

Intermediate External API Calls

Location: Section 6.5, AI provider functions Lines 737-1421

Learn how to make HTTPS requests to external services:

const response = modules.https.post({
    url: 'https://api.anthropic.com/v1/messages',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey,
        'anthropic-version': '2023-06-01'
    },
    body: JSON.stringify(requestBody)
});

if (response.code === 200) {
    const data = JSON.parse(response.body);
}

Intermediate Session Storage

Location: Section 7, document generation ~Line 1450

Learn how to persist data across requests within a user's session:

// Storing data
const session = modules.runtime.getCurrentSession();
session.set({
    name: 'queryResults',
    value: JSON.stringify(results)
});

// Retrieving data (in a later request)
const stored = session.get({ name: 'queryResults' });
const data = JSON.parse(stored);

Intermediate PDF Generation

Location: Section 7, generateDocument() ~Line 1450

Learn how to generate PDFs from templates with dynamic data:

const renderer = modules.render.create();
renderer.addCustomDataSource({
    alias: 'data',
    format: modules.render.DataSource.OBJECT,
    data: { records: queryResults }
});
renderer.templateContent = xmlTemplate;
const pdfFile = renderer.renderAsPdf();

Advanced Custom UI Architecture

Location: Section 9, generateAppHtml() ~Line 2260

Learn the pattern for building single-page applications inside Suitelets using INLINEHTML, including client-server communication with fetch().

Advanced Nested Template Literals

Location: Section 10 Lines 5801-12000

The client-side JavaScript is embedded inside a template literal. This requires special handling:

• No backticks in comments (even // comments)
• Use String.fromCharCode(96) for backtick characters
• Use String.fromCharCode(36) for dollar signs in strings
• Double-escape regex patterns (\\\\s to get \s)

Advanced Plugin Hook System (Beta 09)

Location: Section 3.5 Lines 451-650 (server) and Section 10 ~Line 6200 (client)

Learn how to implement a hook-based extensibility system:

• Topological sorting for dependency resolution
• Version compatibility checking (minAppVersion)
• Synchronous and asynchronous hook execution
• Settings persistence across localStorage and server

Advanced Chart.js Integration (Beta 09)

Location: Section 10 ~Line 10500

Learn how to integrate external visualization libraries:

• Dynamic chart type selection
• Theme-aware color schemes
• Canvas-based rendering and PNG export
• AI-assisted chart configuration

Intermediate Clickable Record Links (Beta 09)

Location: generateRecordLink() ~Line 7700

Learn how to create intelligent links to NetSuite records based on column names and record types:

// Pattern: Detect ID columns and map to record types
const recordTypeMap = {
    'customer': 'customer',
    'entity': 'customer',
    'vendor': 'vendor',
    'item': 'item',
    'transaction': 'transaction',
    // ... more mappings
};

// Generate URL to record
const url = '/app/common/entity/entity.nl?id=' + recordId;

Intermediate RSA-SHA256 JWT Signing (Beta 07)

Location: Section 7.5 ~Lines 1900-2050

Pure JavaScript implementation of RSA-SHA256 for Google Service Account authentication. This is necessary because NetSuite's N/crypto module lacks RSA private key signing:

• ASN.1 DER parser for PKCS#8 private key extraction
• SHA-256 hash implementation
• PKCS#1 v1.5 signature padding
• BigInt modular exponentiation for RSA operation

Beginner Feature Flags (Beta 06)

Location: CONFIG object ~Line 250

Learn how to implement feature toggles that cleanly enable/disable functionality:

const CONFIG = Object.freeze({
    AI_ENABLED: true,       // Master switch for AI features
    PLUGIN_FOLDER_ID: null, // Enable plugin system
    // ... other settings
});

When AI_ENABLED is false, all AI-related UI elements are hidden and server-side AI requests are rejected.

AI Integration Deep Dive

The SuiteQL Query Tool supports seven AI providers plus a custom "OpenAI-Compatible" option for any OpenAI-compatible API. Understanding this architecture helps you integrate external APIs into your own SuiteScript projects.

Supported Providers

OpenAI-Compatible Provider (Beta 09)

The "OpenAI-Compatible" option allows you to use any API that follows the OpenAI chat completions format. This includes:

• OpenRouter - Access to hundreds of models through one API
• Azure OpenAI - Microsoft's hosted OpenAI models
• Together AI - Open-source model hosting
• Ollama - Run models locally
• LM Studio - Local model server
• Any other OpenAI-compatible API endpoint

Configuration requires a custom base URL and model name, making it flexible for enterprise deployments or self-hosted solutions.

Integration Pattern

All AI integrations follow a similar pattern:

1. Receive API key and prompt from client
2. Build request payload according to provider's API spec
3. Make HTTPS POST request using N/https
4. Parse response and extract generated text
5. Return JSON response to client

Schema Explorer Architecture

The Schema Explorer (Lines 13501-16500) is a sophisticated tool that builds a complete picture of your NetSuite database schema.

Key Features

• Client-side schema building - Queries metadata tables to build schema
• IndexedDB persistence - Stores schema locally for fast access
• Role-based visibility - Only shows tables/columns visible to user's role
• 12 export formats (Beta 08):
  • Common formats - JSON, MySQL DDL, PostgreSQL DDL, BigQuery DDL, Snowflake DDL, Markdown
  • Advanced formats - SQLite DDL, SQL Server DDL, Amazon Redshift DDL, dbt YAML, Apache Avro, DBML, Graphviz DOT
• ERD generation - Interactive Mermaid.js diagrams
• Collapsible sections (Beta 09) - Build Schema and Export Schema sections can be collapsed with state persistence

Export Formats (Beta 08)

The Schema Explorer now supports 12 export formats organized into "Common" and "Advanced" groups:

ERD Generation

The ERD viewer uses Mermaid.js to render entity-relationship diagrams. Key concepts:

• Diagrams are generated as Mermaid code, then rendered to SVG
• Zoom/pan handled via CSS transforms with mouse wheel support
• Configurable layout direction (Top-Bottom, Left-Right, etc.)
• Diagram styles: Classic or Hand-drawn
• Export options: SVG, PNG, DOT, Mermaid Live editor
• Scope options: All related tables, Select specific tables, Connected subset

Plugin Architecture

Beta 09 introduced a comprehensive plugin system that allows developers to extend the SuiteQL Query Tool without modifying the core codebase. This is one of the most instructive parts of the application for learning extensibility patterns.

Plugin System Overview

Plugins are self-contained JavaScript or JSON files stored in the NetSuite File Cabinet. The system supports:

• Server-side hooks - Modify queries before/after execution, handle errors
• Client-side hooks - React to UI events, customize display, add functionality
• UI injection points - Insert custom HTML into 17 predefined locations
• Settings persistence - Store plugin configuration in localStorage or File Cabinet
• Feature disabling - Hide built-in UI elements via CSS injection

Enabling Plugins

Set CONFIG.PLUGIN_FOLDER_ID to the internal ID of a File Cabinet folder containing plugin files. Plugin files must be named with *.sqt-plugin.js or *.sqt-plugin.json extension.

Server-Side Hooks

Client-Side Hooks

UI Injection Points (17 total)

Public API for Plugins (SQT Namespace)

// Plugin management
SQT.plugins.register(pluginConfig);
SQT.plugins.get('plugin-id');
SQT.plugins.executeHook('onAfterQuery', data);

// Data access
SQT.getResults();       // Get current query results
SQT.getQuery();         // Read editor content
SQT.setQuery(sql);      // Write to editor
SQT.getEditor();        // Access CodeMirror instance

// UI control
SQT.showModal(id);      // Show a Bootstrap modal
SQT.hideModal(id);      // Hide a modal

Sample Plugin

A sample plugin (query-logger.sqt-plugin.js) is included that demonstrates:

• Server and client hooks
• UI injection with status bar indicator
• Settings with options panel toggle

Data Visualization with Chart.js

Beta 09 added data visualization capabilities powered by Chart.js, allowing users to create charts from query results.

Supported Chart Types

• Bar - Compare values across categories
• Line - Show trends over time or sequence
• Pie - Show proportions of a whole
• Doughnut - Pie variant with center cutout
• Polar Area - Radial chart with equal angles

Chart Configuration

Users can configure charts in two ways:

1. Manual configuration - Select label column (X-axis) and value column(s) (Y-axis)
2. AI-assisted - Describe the desired chart in natural language and let AI configure it

Key Features

• Theme-aware colors - Chart colors adapt to light/dark mode
• Multi-dataset support - Compare multiple value columns
• Automatic numeric detection - Suggests appropriate value columns
• PNG export - Save charts as image files

Integration Pattern

The Chart.js integration demonstrates how to:

• Load an external library (Chart.js via CDN)
• Create a modal-based UI for complex interactions
• Transform query results into chart-compatible data structures
• Handle theme changes dynamically

// Example: Creating a chart from results
const ctx = document.getElementById('chartCanvas').getContext('2d');
new Chart(ctx, {
    type: 'bar',
    data: {
        labels: results.map(r => r[labelColumn]),
        datasets: [{
            label: valueColumn,
            data: results.map(r => r[valueColumn]),
            backgroundColor: getThemeColors()
        }]
    }
});

Suggested Learning Path

Here's a recommended order for exploring the codebase:

Phase 1: Understand the Structure

1. Read the JSDoc decorators at the top of the file Lines 1-5
2. Study the define() call and module imports Lines 321-360
3. Understand the onRequest entry point and how it routes GET vs POST Lines 361-450
4. Review the CONFIG object and feature flags Lines 243-320

Phase 2: Learn Core Operations

1. Study executeQuery() - this is the heart of the application ~Line 660
2. Explore file operations - loading and saving SQL files Lines 781-910
3. Understand handlePostRequest() and the dispatch pattern ~Line 410

Phase 3: Advanced Patterns

1. Study external API calls in the AI generation section Lines 961-1650
2. Explore PDF generation with the render module ~Line 1660
3. Understand session storage for multi-step processes
4. Study RSA-SHA256 JWT signing for Google Sheets export ~Lines 1900-2050

Phase 4: UI Architecture

1. See how INLINEHTML is used to inject custom HTML ~Line 2260
2. Study the client-side JavaScript and its communication with the server Lines 5801-12000
3. Understand the fetch() pattern for AJAX calls
4. Explore Chart.js integration for data visualization ~Line 10500

Phase 5: Extensibility (Beta 09)

1. Study the plugin system server-side hooks Lines 451-650
2. Explore client-side plugin API (SQT namespace) ~Line 6200
3. Understand UI injection points for extending the interface
4. Review the sample plugin (query-logger.sqt-plugin.js) for practical examples

Glossary of NetSuite Terms

NetSuite has its own vocabulary. Here are key terms you'll encounter:

Deployment Walkthrough

Here's how to deploy the SuiteQL Query Tool (or any Suitelet) to NetSuite:

Step 1: Upload the Script File

1. Go to Documents > Files > File Cabinet
2. Navigate to SuiteScripts folder (create if needed)
3. Click Add File and upload the script

Step 2: Create the Script Record

1. Go to Customization > Scripting > Scripts > New
2. Select the uploaded script file
3. Fill in: Name, ID, Description
4. Click Save

Step 3: Create a Deployment

1. On the Script record, go to Deployments subtab
2. Click New Deployment
3. Set: Title, ID, Status (Released), Log Level
4. On Audience subtab, select allowed roles
5. Click Save

Step 4: Access the Suitelet

Click the URL link on the deployment record to open the tool.

Common Errors & Troubleshooting

SSS_USAGE_LIMIT_EXCEEDED

Solutions: Reduce operations, use getRemainingUsage() to monitor, or use Map/Reduce for large operations.

Invalid Column / Invalid Table

Solutions: Check column/table names in Analytics Browser, verify role permissions, column names are case-sensitive.

Search Timed Out

Solutions: Add restrictive WHERE clauses, remove unnecessary JOINs, avoid SELECT *, add date range filters.

SuiteQL Quick Reference

Common Tables

Useful Functions

-- Get display value instead of internal ID
BUILTIN.DF( Transaction.status ) AS StatusName

-- Handle NULL values
NVL( Customer.phone, 'No Phone' ) AS Phone

-- Date formatting
TO_CHAR( Transaction.trandate, 'YYYY-MM-DD' ) AS FormattedDate

-- Current date
SYSDATE

-- Limit rows (no LIMIT keyword in SuiteQL!)
WHERE ROWNUM <= 100

Security Best Practices

1. Always Use Parameterized Queries

// GOOD - Parameterized (safe)
query.runSuiteQL({
    query: 'SELECT * FROM Customer WHERE id = ?',
    params: [customerId]
});

// BAD - String concatenation (SQL injection risk!)
query.runSuiteQL({
    query: 'SELECT * FROM Customer WHERE id = ' + customerId
});

2. Never Expose API Keys in Client-Side Code

Store keys in Script Parameters or have users enter them (stored in session).

3. Validate and Sanitize Input

Always validate data from external sources before using it.

Debugging Tips

1. Use the Execution Log

log.debug({ title: 'Debug', details: myVariable });
log.error({ title: 'Error', details: e.message });

View logs: Script Deployment record → View Execution Log

2. Browser Developer Tools

For client-side JavaScript: Console, Network tab, Sources tab for breakpoints.

3. Check Governance

const remaining = runtime.getCurrentScript().getRemainingUsage();
log.debug('Governance remaining', remaining);

Frequently Asked Questions

Q: Why can't I use LIMIT like in MySQL?

A: SuiteQL is based on Oracle SQL. Use ROWNUM instead: WHERE ROWNUM <= 10

Q: How do I find table and column names?

A: Use Analytics Browser in NetSuite, the Tables Reference in this tool, or query OA_TABLES.

Q: Can I INSERT, UPDATE, or DELETE with SuiteQL?

A: No. SuiteQL is read-only. Use the N/record module to modify data.

Q: Why do I get numbers instead of names for some fields?

A: Use BUILTIN.DF(field) to get the display value instead of internal ID.

Q: How do I enable the plugin system?

A: Set CONFIG.PLUGIN_FOLDER_ID to the internal ID of a File Cabinet folder. Place plugin files (*.sqt-plugin.js or *.sqt-plugin.json) in that folder.

Q: How do I disable AI features?

A: Set CONFIG.AI_ENABLED to false. This hides all AI-related UI elements and rejects AI requests on the server.

Q: Can I use my own AI model or API?

A: Yes! Use the "OpenAI-Compatible" provider option to connect to any API that follows the OpenAI chat completions format (OpenRouter, Azure OpenAI, Ollama, etc.).

Q: How do I create charts from query results?

A: Click the "Chart" button in the results toolbar after running a query. Select chart type and configure the label/value columns, or describe what you want and let AI configure it.

Q: Why don't ID columns link to records?

A: The "Link IDs to records" option may be disabled in the Options panel. Enable it to automatically create clickable links for customer, vendor, employee, item, and transaction IDs.

Printable Cheat Sheet

BUILTIN.DF(field)
NVL(field, default)
TO_DATE('2024-01-01', 'YYYY-MM-DD')
SYSDATE
ROWNUM

SQT.getResults()
SQT.getQuery() / setQuery()
SQT.plugins.register(config)
SQT.showModal(id)

Additional Resources

Official Documentation

• SuiteScript 2.x API Reference
• SuiteQL Documentation
• N/query Module

Community Resources

• Stack Overflow - SuiteScript Tag
• Tim Dietrich's SuiteQL Blog Posts